How to Write a Mouse Listener

Mouse events notify when the user uses the mouse (or similar input device) to interact with a component. Mouse events occur when the cursor enters or exits a component's onscreen area and when the user presses or releases one of the mouse buttons.

Tracking the cursor's motion involves significantly more system overhead than tracking other mouse events. That is why mouse-motion events are separated into Mouse Motion listener type (see How to Write a Mouse Motion Listener).

To track mouse wheel events, you can register a mouse-wheel listener. See How to Write a Mouse Wheel Listener for more information.

If an application requires the detection of both mouse events and mouse-motion events, use the MouseInputAdapter class. This class implements the MouseInputListener, a convenient interface that implements the MouseListener and MouseMotionListener interfaces. However, the MouseInputListener interface does not implement the MouseWheelListener interface.

Alternatively, use the corresponding AWT MouseAdapter class, which implements the MouseListener, MouseMotionListener, and MouseWheelListener interfaces.

The following example shows a mouse listener. At the top of the window is a blank area (implemented by a class named BlankArea). The mouse listener listens for events both on the BlankArea and on its container, an instance of MouseEventDemo. Each time a mouse event occurs, a descriptive message is displayed under the blank area. By moving the cursor on top of the blank area and occasionally pressing mouse buttons, you can fire mouse events.

You can find the demo's code in MouseEventDemo.java and BlankArea.java. Here is the demo's mouse event handling code:

public class MouseEventDemo ... implements MouseListener {
        //where initialization occurs:
        //Register for mouse events on blankArea and the panel.
        blankArea.addMouseListener(this);
        addMouseListener(this);
    ...

    public void mousePressed(MouseEvent e) {
       saySomething("Mouse pressed; # of clicks: "
                    + e.getClickCount(), e);
    }

    public void mouseReleased(MouseEvent e) {
       saySomething("Mouse released; # of clicks: "
                    + e.getClickCount(), e);
    }

    public void mouseEntered(MouseEvent e) {
       saySomething("Mouse entered", e);
    }

    public void mouseExited(MouseEvent e) {
       saySomething("Mouse exited", e);
    }

    public void mouseClicked(MouseEvent e) {
       saySomething("Mouse clicked (# of clicks: "
                    + e.getClickCount() + ")", e);
    }

    void saySomething(String eventDescription, MouseEvent e) {
        textArea.append(eventDescription + " detected on "
                        + e.getComponent().getClass().getName()
                        + "." + newline);
    }
}

The Mouse Listener API

The MouseListener Interface

The MouseAdapter class (the AWT adapter class) is abstract. All its methods have an empty body. So a developer can define methods for events specific to the application. You can also use the MouseInputAdapter class, which has all the methods available from MouseListener and MouseMotionListener.

The MouseEvent Class

The InputEvent Class

The MouseEvent class inherits many useful methods from InputEvent and a couple handy methods from the ComponentEvent and AWTEvent classes.

(mouseEvent.getModifiers() & InputEvent.BUTTON3_MASK)
== InputEvent.BUTTON3_MASK

if (event.getModifiersEx() & (BUTTON1_DOWN_MASK |
                              BUTTON2_DOWN_MASK |
                              BUTTON3_DOWN_MASK)
                               == BUTTON1_DOWN_MASK) {
    ...
}

The MouseInfo Class

The MouseInfo class provides methods to obtain information about the mouse pointer location at any time while an application runs.